import { CodeBlockTransformer, Link } from '@brillout/docpress'

Adding a filename suffix `.server.js` / `.client.js` / `.shared.js` to a file has following effect:
 - For all files, it *guarantees* in which environment the file is loaded.
 - For <Link href="/config#files">`+` files</Link>, it *determines* in which environment the file is loaded.

See also <Link href="/config#clear-js" doNotInferSectionTitle noBreadcrumb /> and <Link href="/config#default-js" doNotInferSectionTitle noBreadcrumb />.

## For all files

### `.server.js`

The most common use case for `.server.js` is to ensure that a file that contains secret information is never accidentally leaked to the client-side (and thus made public).

```ts
// /server/database/credentials.server.ts

// This file should *never* be imported by client-side code.
// We use .server.ts to guarantee that.
export default {
  password: 'WLa!9HW?E10a'
}
```

> In this example, it's crucial that `credentials.server.js` is never loaded by the client-side: otherwise, because client-side JavaScript is public, everyone could read the password defined in `credentials.server.js`.

If some client-side code does load `credentials.server.js` then Vike throws an error and aborts any attempt to build for production. (In development Vike shows a warning.)

<CodeBlockTransformer lineBreak="white-space">
```
[vike][Wrong Usage] Server-only module /server/database/credentials.server.js (https://vike.dev/file-env) imported on the client-side by /pages/product/@id/+Page.js
```
</CodeBlockTransformer>


### `.client.js`

You can use `.client.js` to ensure that a file always runs on the client-side.

```ts
// /utils/someClientCode.client.ts

// This code only works in the browser; we use .client.ts to assert that this file is
// never loaded on the server-side.

window.onclick = () => {
  // ...
}
```

### `.shared.js`

The file extension `.shared.js` has an effect only for `+` files (see section below): it's useless for other files.


## For `+` files

For <Link href="/config#files">`+` files</Link>, the most common use case is to change the environment of <Link href="/hooks">Vike hooks</Link>. Most notably the <Link href="/data">`data()` hook</Link>: by renaming `+data.js` to `+data.shared.js`/`+data.server.js`/`+data.client.js` you tell Vike in which environment `data()` should be loaded and executed, see <Link href="/data#environment" />.

> Essentially, it's a simpler way to set the <Link href="/meta#example-modify-data-env">`meta.env` setting</Link> of a `+` file.
> Adding `.server.js`/`.client.js`/`.shared` to a `+` file, for example `/pages/product/@id/+data.js`, is equivalent to:
>
> ```ts
> // /pages/product/@id/+config.ts
>
> import type { Config } from 'vike/types'
>
> export default {
>   meta: {
>     data: {
>       // .shared.js
>       env: { server: true, client: true },
>       // .server.js
>       env: { server: true, client: false },
>       // .client.js
>       env: { server: false, client: true }
>     }
>   }
> } satisfies Config
> ```


## See also

- <Link href="/config#clear-js" doNotInferSectionTitle />
- <Link href="/config#default-js" doNotInferSectionTitle />
- <Link href="/meta" />
